WoMan is a browser for traditional Unix-style manual page
documentation. Each such document is conventionally referred to
as a manual page, or man page for short,
even though some are very much longer than one page. A man page
is a document written using the Unix “man” macros,
which are themselves written in the nroff/troff text processing
markup language. nroff and troff are
text processors originally written for the UNIX operating system
by Joseph F. Ossanna at Bell Laboratories, Murray Hill, New
Jersey, USA. They are closely related, and except in the few
cases where the distinction between them is important I will
refer to them both ambiguously as roff.
roff markup consists of requests and
escape sequences. A request occupies a complete line
and begins with either a period or a single forward quote. An
escape sequences is embedded within the input text and begins (by
default) with a backslash. The original man macro package defines
20 new roff requests implemented as macros, which
were considered to be sufficient for writing man pages. But
whilst in principle man pages use only the man macros, in
practice a significant number use many other roff
requests.
The distinction between troff and
nroff is that troff was designed to
drive a phototypesetter whereas nroff was designed
to produce essentially ASCII output for a
character-based device similar to a teletypewriter (usually
abbreviated to “teletype” or “tty”).
Hence, troff supports much finer control over output
positioning than does nroff and can be seen as a
forerunner of TeX. Traditionally, man pages are either formatted
by troff for typesetting or by nroff
for printing on a character printer or displaying on a screen. Of
course, over the last 25 years or so, the distinction between
typeset output on paper and characters on a screen has become
blurred by the fact that most screens now support bit-mapped
displays, so that any information that can be printed can also be
rendered on screen, the only difference being the resolution.
Nevertheless, Unix-style manual page documentation is still
normally browsed on screen by running a program called
man. This program looks in a predefined set of
directories for the man page matching a specified topic, then
either formats the source file by running nroff or
recovers a pre-formatted file, and displays it via a pager such
as more. nroff normally formats for a
printer, so it paginates the output, numbers the pages, etc.,
most of which is irrelevant when the document is browsed as a
continuous scrollable document on screen. The only concession to
on-screen browsing normally implemented by the man
program is to squeeze consecutive blank lines into a single blank
line.
For some time, Emacs has offered an improved interface for
browsing man pages in the form of the Emacs man (or
manual-entry) command, see man. This command
runs man as described above, perhaps in the
background, and then post-processes the output to remove much of
the nroff pagination such as page headers and
footers, and places the result into an Emacs buffer. It puts this
buffer into a special major mode, which is tailored for man page
browsing, and provides a number of useful navigation commands,
support for following references, etc. It provides some support
for special display faces (fonts), but no special menu or mouse
support. The Emacs man package appears to have been developed
over about 10 years, from the late 1980s to the late 1990s.
There is considerable inefficiency in having
nroff paginate a document and then removing most of
the pagination!
WoMan is an Emacs Lisp library that provides an emulation of
the functionality of the Emacs man command, the main
difference being that WoMan does not use any external programs.
The only situation in which WoMan might use an external program
is when the source file is compressed, when WoMan will use the
standard Emacs automatic decompression facility, which does call
an external program.
I began developing WoMan in the Spring of 1997 and the first
version was released in May 1997. The original motivation for
WoMan was the fact that many GNU and Unix programs are ported to
other platforms and come with Unix-style manual page
documentation. This may be difficult to read because ports of the
Unix-style man program can be a little awkward to
set up. I decided that it should not be too hard to emulate the
20 man macros directly, without treating them as
macros and largely ignoring the underlying roff
requests, given the text processing capabilities of Emacs. This
proved to be essentially true, and it did not take a great deal
of work to be able to format simple man pages acceptably.
One problem arose with the significant number of man pages
that use roff requests in addition to the
man macros, and since releasing the first version of
WoMan I have been continually extending it to support more
roff requests. WoMan can now format a significant
proportion of the man pages that I have tested, either well or at
least readably. However, I have added capabilities partly by
making additional passes through the document, a design that is
fundamentally flawed. This can only be solved by a major
re-design of WoMan to handle the major formatting within a single
recursive pass, rather than the present multiple passes without
any significant recursion. There are some roff
requests that cannot be handled satisfactorily within the present
design. Some of these are currently handled by kludges that
“usually more or less work.”
The principle advantage of WoMan is that it does not require
man, and indeed the name WoMan is a contraction of
“without man.” But it has other advantages. It does
not paginate the document, so it does not need to un-paginate it
again, thereby saving time. It could take full advantage of the
display capabilities available to it, and I hope to develop WoMan
to take advantage of developments in Emacs itself. At present,
WoMan uses several display faces to support bold and italic text,
to indicate other fonts, etc. The default faces are also colored,
but the choice of faces is customizable. WoMan provides menu
support for navigation and mouse support for following
references, in addition to the navigation facilities provided by
man mode. WoMan has (this) texinfo
documentation!
WoMan does not replace man, although it
does use a number of the facilities implemented in the Emacs
man library. WoMan and man can happily co-exist,
which is very useful for comparison and debugging purposes.
nroff simulates non-ASCII
characters by using one or more ASCII
characters. WoMan should be able to do much better than this. I
have recently begun to add support for WoMan to use more of the
characters in its default font and to use a symbol font, and it
is an aspect that I intend to develop further in the near future.
It should be possible to move WoMan from an emulation of
nroff to an emulation of troff as GNU
Emacs moves to providing bit-mapped display facilities.